MEDB 5501, Module08

Topics to be covered

What you will learn
- History of R
- Installing R
- Objects in R
- Anatomy of a small R program
- Live demonstration
- Good programming practices
- Your programming assignment

History of R

Break #1

What you have learned
- History of R
What’s coming next
- Installing R

Special note

This slide show was created using R.
- Not complicated
- But beyond scope of this class
Source
- https://github.com/pmean/introduction-to-r/tree/master/part1/src
A second resource
- http://blog.pmean.com/powerpoint-with-r-markdown/

Okay. Let’s get started.

If you are viewing this presentation, I need to point out that it was developed using R. The process is not very complicated, but it is beyond the scope of this class.

I do want to note that I have switched recently from doing presentations using Powerpoint to presentations using reveal.js. I really like reveal.js, for a whole host of reasons that are hard to explain. The only difference that you might notice is that the presentations using reveal.js are html files. That means that you open them up using a web browser rather than Powerpoint.

If you are curious, you can look at the code that I used to develop this PowerPoint presentation. It’s all on my github site.

But don’t feel obligated to look at it. You will not be responsible for any of this in an introductory class.

It may seem a bit weird to have an R program that creates a presentation that talks about a different R program, but it works well for me.

Installing R (https://cran.r-project.org/)

Screenshot of webpage for installation of R

Installing RStudio (https://rstudio.com/)

Screenshot of main page for RStudio

Installing RStudio (https://rstudio.com/)

Screenshot of products of RStudio

Installing R and R Studio

R is required
RStudio is strongly recommended
Do not delay in getting this software installed
Find me if you have ANY problems

Recommended directory structure

Screenshot of the directory structure I use

“A place for everything, everything in its place”

data
- raw/intermediate data files
doc
- documentation
images
- graphs
results
- program output
src
- program code

The quote at the top of the slide is an organizational principle espoused by Benjamin Franklin. If you’ve seen my office, you’ll know that I am probably the last person to lecture you on organization. But I have found that a standardized directory structure has made my life a lot easier.

The data folder contains any raw data files. It’s also where I put intermediate files, files that I create and save for later re-use. Some people put intermediate files in the results folder, and that’s a fine alternative. Just be sure to be consistent about it.

The doc folder contains any documentation associated with the work. The IRB approved protocol, if I have one, will go here. If I am working with someone and they send me a paper that helps describe the type of data analysis they want, I put it in this folder. I also print key emails from the other team members to pdf format and store them here as well.

If my programs produce any graphs, I will store them in the images folder. I use screenshots of various web pages a lot in my work and I put those here as well.

I usually store program output in the results folder, but not always, for reasons I don’t want to get into.

The program code goes in the src folder.

This directory structure has an extra folder, and that’s always okay. This folder, modules, contains some of the information on homework assignments, quizzes, and so forth.

I adopted the structure about four years ago. I do not do a lot of collaborative research but I do find myself frequently revisiting a project six months or year down the road. Having a common directory structure means that I can very quickly and rapidly identify the stuff that was done before and the stuff that needs to change for the new work.

I would strongly encourage you to set up a directory structure like this one.

Break #2

What you have learned
- Installing R
What’s coming next
- Objects in R

Introduction

This is a very brief introduction to the basic objects in R.

[1] "R version 4.3.0 (2023-04-21 ucrt)"

[1] "2024-12-28"

Functions

[1] 1.732051

[1] 1.000000 1.414214 1.732051 2.000000 2.236068

Nested functions and pipes

[1] 1.249046

[1] 1.249046

Named arguments in functions

[1] 134.8952

[1] 134.8952

[1] 2.326348

Scalars

[1] 3

[1] "R"

[1] "3"

Vectors

[1] 1 2 3

[1] "a" "b" "c"

[1] "a" "2"

Naming vectors

  BA   MS  PhD 
1977 1978 1982

    first_name middle_initial      last_name 
     "Stephen"            "D"        "Simon"

Matrices using cbind and rbind functions

     [,1] [,2]
[1,]    1    4
[2,]    2    5
[3,]    3    6

     [,1] [,2] [,3]
[1,]    1    2    3
[2,]    4    5    6

Matrices using the matrix function

     [,1] [,2] [,3]
[1,]    1    2    3
[2,]    4    5    6

Lists

[[1]]
[1] 3

[[2]]
[1] "a" "b" "c"

[[3]]
     [,1] [,2] [,3]
[1,]    1    2    3
[2,]    4    5    6

Lists using names

$name
    first_name middle_initial      last_name 
     "Stephen"            "D"        "Simon" 

$degrees
  BA   MS  PhD 
1977 1978 1982 

$age
[1] 64

Data frames

  vector_example_1 vector_example_2
1                1                a
2                2                b
3                3                c

Naming data frame columns

  c.1..2..3. c..a....b....c..
1          1                a
2          2                b
3          3                c

  small_numbers early_letters
1             1             a
2             2             b
3             3             c

Tibbles

# A tibble: 3 × 2
      x y    
  <dbl> <chr>
1     1 a    
2     2 b    
3     3 c

Break #3

What you have learned
- Objects in R
What’s coming next
- Anatomy of a small R program

Anatomy of a small R program, overview

YAML header

---
title: "Illustrating the structure of an R program"
editor: source
format: 
  html:
    embed-resources: true
execute: 
  error: true
---

All right, The first thing we have is the header. The header uses a structure called YAML (Y-A-M-L). YAML is a special type of up format that is used by lots of programmers. The header provides a bit of information about the about the program. The default option when you start up a new R Markdown file is to list, the title, author, date, and output format.

I find the word “date” by itself ambiguous, so I add the word “Created” to distinguish the creation date from the last modified date. It is not easy to track the last modified date in RStudio.

Quarto has options for creating web pages (html documents). You can also produce Word documents and PDF documents. I should warn you that creating PDF documents directly is a bit tricky. You need to have a program called LaTeX (pronounced lay-tech) installed first.

You can also produce Powerpoint files, which this is an example of.

The default is HTML and that’s a pretty good format. Quite honestly, I’ve got a lot of mileage out of HTML. It has some limitations compared to other formats, but it is so much simpler to create and maintain the code that produces HTML files.

First comment


This program was written by Steve Simon  and created on 2019-01-28 with a major
revision on 2024-12-27. It is used to illustrate the structure of an R program. 
This program is in the public domain. You can use it any way that you please.

First code chunk

```{r}
#| label: setup
#| message: false
#| warning: false

R.version.string
Sys.Date()
library(tidyverse)
```

In quarto, sections of R code are delineated with three backticks. The backtick is a leftward slanting single quote mark. For most keyboards, you will find the backtick key on the top row, just to the left of the “1” key.

The beginning of a chunk of R code has three backticks, followed by a left curly bracket, the letter “r” and then an optional name. End with a right curly bracket.

This program chunk includes two lines of code.

R.version.string displays the version of R that you are running. You should try to use a version of R at 4.0 or higher. This would only be an issue if you’ve been using R for more than a couple of years and have been lazy about upgrades. If you downloaded R at the beginning of this semester, you will have a version of R beyond 4.0.

The second line of code, Sys.Date(), displays the current date. Sometimes knowing when a program was run can help you decide if you need to run the program again (perhaps because the data has changed, or you are using a new version of R).

After this you see three more backticks, which tells R Markdown that the chunk of code has ended.

I recommend that you try to avoid long stretches of R code. Break it up into segments of no more than 20 lines of code, and often less than this is better. Working with your program in chunks and interspersing free text comments liberally makes it easier to maintain your code.

Second comment


Read data from the aids-cases text file. This file is described at

https://github.com/pmean/data/blob/main/files/aids-cases.yaml

Second code chunk

```{r}
#| label: read-text-file

aids_cases <- read_csv(
  file="../data/aids-cases.csv",
  col_types="nnn")
glimpse(aids_cases)
```

Here’s some more R code. I named the chunk “read-rdata-file”. The load function reads information from a file named ../data.two-small-dataframes.RData.

I have to apologize here because Powerpoint splits the load function onto two consecutive lines, making it a bit harder to read.

The second line of code is the ls function. Just ls with a left and a right parenthesis. This function lists everything that you have either loaded or created within R. In this case, it is just the information that we got from the two-small-dataframes.RData file.

There are two objects, bump and fat. These are actually dataframes, the standard way that R stores data. If you look on my github site, you will find data dictionaries for these two dataframes.

The head function lists the first few lines of ant object in R. In this case, it will show the first six lines of the dataframe bump.

Third comment


This is a small dataset with only three variables. Now let's draw a line graph.

After the second chunk of R code, I add a couple of extra comments.

It’s very simple program but if you can get this program to run, you probably have smooth sailing for the rest of the class. I really believe that installing the software is often tricky. Getting the first program to run is often tricky. But once you get those going then you keep on modifying. Just make tiny changes to the programs you already have. It will either work or there will be an obvious error that you can fix.

The problem is getting the first program will run. Once you get one program that works, the rest is downhill.

I need to emphasize here very strongly if you’re having problems. Come and see me right away. Drop me an email. Try to visit. I do not have official office hours, but I will make appointments at any reasonable time for people to come and talk.

Third code chunk

```{r}
#| label: line-graph

aids_cases |>
  ggplot() +
    aes(yr, nsw) +
    geom_line()
```

Fourth comment


There is an increasing trend in aids cases in New South Wales over time.

Anatomy of a small program, review

Output, overview

Output, part 1

First part of output, header and information about this file

Output, part 2

Second part of output, reading in the data

Output, part 3

Break #4

What you have learned
- Anatomy of a small R program
What’s coming next
- Live demonstration

Live demonstration of running R

In this segment, you will see a live demonstration running the program simon-5505-01-template.qmd.

Break #5

What you have learned
- Live demonstration
What’s coming next
- Good programming practices

General requirements for any program

There are standards in six areas:

Documentation
Graphs
Tables
Readability
Interpretation
Conciseness

There may be times when one or two of these standards do not apply. Which standards apply and which don’t should be obvious from the nature of the programming assignment.

Documentation is required!

Documentation should include

the name of the author (you!),
the creation date,
the purpose of your program, and
any restrictions on use (your choice).
- Public domain (no restrictions)
- Specific restrictions on how others can use your program

Graphs cannot rely on default choices, 1

Always modify your graphs. Do not settle for the default options.

Include your name and date on the title of any graph
- “Steve Simon produced this graph on 2023-09-19.”
Avoid the display of unnecessary decimal places on the axes
Use comma separators for large numbers
Replace category codes with descriptive labels

Graphs cannot rely on default choices, 2

Replace short variable names with longer descriptors
- Include units of measurement, if needed
Avoid the gratuitous use of color
- Unless needed to distinguish between groups
- Fill boxes and points with white/transparent colors

Tables also need modification

Round to two or three significant figures
Use comma separators if numbers are >= 1,000
Avoid scientific notation (e.g., 1.23E-04)
Avoid small p-values (e.g., p=0.000)
- Change to p<0.001
Suppress the printing of unneeded tables
- Sometimes difficult

Sometimes default tables/graphs acceptable

Early assignments may ask for defaults
Always round and specify units in your interpretations

Your code must be easy to read

Make liberal use of
- blank lines
- line breaks
- indenting
- vertical lists

Always include an interpretation

Use simple evaluative words
- Young/Elderly
- Less than half/more than half
- Almost all/almost none
- Substantial improvement/roughly comparable
Depends on context
- No penalty for subjective judgments

Conciseness

Do not include analyses that were not asked for
Avoid displaying excessively large tables
- This may be difficult for SAS and SPSS

Data dictionary

If you include a data set that you found on your own rather than one that your instructors provided, you must include a data dictionary. The elements of a data dictionary should include:

Source
Description
Copyright
Size
Variables

Data dictionary: source

Where did you find the data
- Website link
- Formal reference (if available)

Include a complete URL, except if your data is behind a paywall. If your data is associated with a peer-reviewed publication, provide a formal reference to that publication.

Data dictionary: Description

Provide a few sentences explaining the context of your data. Explain how the data was collected and what it is being used for.

Data dictionary: Copyright

On the Internet, many datasets do not specify copyright: the conditions under which you can use the data. If copyright information is available, it might take several forms:

Public domain
- Use the data any way you wish
Copyright
- Do not use without permission
Open source license
- Use the data with just a few restrictions
  - Cite the original source, CC-By
  - No commercial re-use CC-By-NC
  - Do not modify CC-By-ND

Data dictionary: Size

Number of rows (excluding a header row)
Number of columns

Data dictionary: Variables

Name
Label
Units of measure

Data dictionary: Variable scale

Scale
- Nominal
- Ordinal
- Interval
- Ratio

Data dictionary: Variable range

Range
- Non-negative (>= 0)
- Positive (> 0)
- Upper bound, if any

Data dictionary: Variable type

Type
- Integer
- Float
- Character

File details

This file was written by Steve Simon on 2024-12-26. It is in the public domain and you can use it any way you please.

Break #6

What you have learned
- Good programming practices
What’s coming next
- Your programming assignment

Program

Download the program template
- Store it in your src folder
Modify the file name
- Use your last name instead of “simon”
- Change “template” to “aids-cases”
Modify the documentation headers
- Add your name
- Optional: change the copyright statement

Data

Download the data file
- Store it in your data folder
Refer to the data dictionary, if needed.

Question 1

Calculate the minimum and maximun number of AIDS cases in Victoria from 1982 to 1987. The default format for this table is acceptable. Provide a brief interpretation.

Question 2

Graph the trend in AIDS cases in Victoria from 1982 to 1987. Use a nice format and provide a brief interpretation.

Grading rubric

You will be evaluated using the general grading rubric for programming assignments.

Your submission

Save the output in html format
Convert it to pdf format.
Make sure that the pdf file includes
- Your last name
- The number of this course
- The number of this module
Upload the file

If it doesn’t work

Please review the suggestions if you encounter an error page.

File details

This programming assignment was written by Steve Simon on 2024-12-18 and is placed in the public domain.

Summary

What you have learned
- History of R
- Installing R
- Objects in R
- Anatomy of a small R program
- Live demonstration
- Good programming practices
- Your programming assignment